Build data is not used when determining instance sequence #3363

paigecalvert · 2025-07-07T20:57:27Z

Previews:

About using semver: https://deploy-preview-3363--replicated-docs.netlify.app/vendor/releases-about#semantic-versioning
Description of how version precedence works with/without SemVer https://deploy-preview-3363--replicated-docs.netlify.app/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence
Description of instance sequence: https://deploy-preview-3363--replicated-docs.netlify.app/vendor/releases-about#admin-console-instance-sequence

…cendence

netlify · 2025-07-07T20:57:31Z

✅ Deploy Preview for replicated-docs ready!

Name	Link
🔨 Latest commit	`1d5a906`
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs/deploys/686d605dbc46150008dfe786
😎 Deploy Preview	https://deploy-preview-3363--replicated-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-07-07T20:57:32Z

✅ Deploy Preview for replicated-docs-upgrade ready!

Name	Link
🔨 Latest commit	`1d5a906`
🔍 Latest deploy log	https://app.netlify.com/projects/replicated-docs-upgrade/deploys/686d605dd1b76f00088049e2
😎 Deploy Preview	https://deploy-preview-3363--replicated-docs-upgrade.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

docs/vendor/releases-about.mdx

paigecalvert · 2025-07-07T21:01:30Z

docs/vendor/releases-about.mdx

+    - 2.12.0
+    - 2.12.0-2
+    - 2.12.0-1
+    - 2.11.0


^ added this from your example here https://github.com/replicated-collab/itrs-replicated/issues/233#issuecomment-3044541549

paigecalvert · 2025-07-07T21:01:55Z

docs/vendor/releases-about.mdx

-Releases promoted to a channel with semantic versioning enabled are verified to ensure that the release version label is a valid semantic version. For more information about valid semantic versions, see [Semantic Versioning 2.0.0](https://semver.org).
+    :::note
+    Build metadata in the semantic version string is ignored when determining version precedence. For example, the Admin Console interprets 2.12.0, 2.12.0+1, and 2.12.0+2 as the same version. Instead of using build metadata in your semantic version labels, Replicated recommends that you increment the patch version. Or, use pre-release identifiers. For example, 1.0.0-alpha or 1.0.0-1.
+    :::


^ added note to call out how build metadata isn't considered in precedence calculations

paigecalvert · 2025-07-07T21:02:19Z

docs/vendor/releases-about.mdx


-Semantic versioning is recommended because it makes versioning more predictable for users and lets you enforce versioning so that no one uses an incorrect version.
+* For channels _with_ SemVer enabled, the Admin Console sequences releases by their semantic version. For information about how precedence is determined in SemVer, see [11. 
+Precedence refers to how versions are compared to each other when ordered](https://semver.org/#spec-item-11) in the Semantic Versioning 2.0.0 documentation.


^ added this link to the info on precedence in the semver docs

docs/vendor/releases-creating-channels.md

paigecalvert · 2025-07-07T21:03:24Z

static/images/semver-graphic.png

Added this graphic from the Commercial Software Distribution Lifecycle Handbook to enhance the description of what semver is

docs/vendor/releases-about.mdx

paigecalvert · 2025-07-08T18:18:06Z

docs/vendor/releases-about.mdx

+The purpose of the instance sequence number is to help the user track all new versions across upstream updates, config changes, and license syncs. Without the instance sequence number, this could be challegning as the version label does not change when the user makes config changes or syncs their license.

-If releases without a valid semantic version are already promoted to a channel, the Admin Console sorts the releases that do have semantic versions starting with the earliest version and proceeding to the latest. The releases with non-semantic versioning stay in the order of their promotion dates. For example, assume that you promote these releases in the following order to a channel: 
+The instance sequence number does _not_ reflect version precedence. The Admin Console determines version precedence based on either the release's version label (if semantic versioning is enabled) or based on the date and time the release was promoted (if semantic versioning is disabled). This is important because precedence controls which versions are available to customers for upgrade. It also determines how versions are ordered on the Admin Console **Version history** page. For more information, see [How the Admin Console Determines Version Precedence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence) in _Performing Updates in Existing Clusters_.


^ added this paragraph to differentiate between instance sequence number and version precedence

It includes a link to more info about how version precedence is calculated

paigecalvert · 2025-07-08T18:18:49Z

docs/vendor/releases-about.mdx

+When a new version is available for upgrade (including when KOTS checks for upstream updates, when the user syncs their license, or when the user makes a config change) the KOTS Admin Console assigns a unique instance sequence number to that version. The instance sequence number starts at 0 and increments for each identifier that is returned when a new version is available.

-For channels with semantic versioning enabled, the Admin Console sequences instance releases by their semantic versions instead of their promotion dates.
+The purpose of the instance sequence number is to help the user track all new versions across upstream updates, config changes, and license syncs. Without the instance sequence number, this could be challegning as the version label does not change when the user makes config changes or syncs their license.


^ added this paragraph to explain the purpose of instance sequence (curious for feedback as this is basically my own understanding)

paigecalvert · 2025-07-08T18:28:29Z

docs/vendor/releases-about.mdx

+You can enable and disable SemVer for releases on each channel in the channel settings. When you enable SemVer on a channel, the Vendor Portal checks all releases promoted to that channel to verify that the version label is valid SemVer. For more information about how to enable SemVer on a channel, see [Enable Semantic Versioning](/vendor/releases-creating-channels#enable-semantic-versioning) in _Create and Edit Channels_.

-[View a larger version of this image](/images/release-sequences.png)
+When SemVer is enabled, the Admin Console uses the version labels that you assign to releases to determine release precedence. This is important because precedence controls which versions are available to customers for upgrade. It also determines how versions are ordered on the Admin Console **Version history** page. For more information, see [How the Admin Console Determines Version Precedence](/enterprise/updating-app-manager#how-the-admin-console-determines-version-precedence) in _Performing Updates in Existing Clusters_.


^ Added this paragraph to explain how enabling semver likely affects the version precedence on the Admin Console version history page, with a link to more info

paigecalvert · 2025-07-08T18:30:09Z

docs/enterprise/updating-app-manager.mdx

-    For help information, run `kubectl kots admin-console upgrade -h`. 
+    For help information, run `kubectl kots admin-console upgrade -h`. 
+
+## How the Admin Console Determines Version Precedence


^ I decided to try out moving this info over to the Performing Updates with KOTS in Existing Clusters page (rather than in About Channels and Releases).
This info was feeling pretty specific to updating with kots/viewing the Admin Console version history page, and probably isn't something most people would be needing to read out in a high level overview of channels and releases

I linked to this section from a couple places, as you'll see below

paigecalvert · 2025-07-08T18:30:55Z

docs/enterprise/updating-app-manager.mdx

+
+## How the Admin Console Determines Version Precedence
+
+The Admin Console uses version precedence to determine which versions are available for upgrade. Version precedence also determines the order in which versions are displayed on the **Version history** page, as shown in the example below:


^ added this explanation of what version precedence is/how it's used

Add info about how build data is not used when determining semver pre…

70f0916

…cendence

paigecalvert requested a review from a team as a code owner July 7, 2025 20:57

replicated-ci added type::docs Improvements or additions to documentation type::feature labels Jul 7, 2025

paigecalvert changed the title ~~Add info about how build data is not used when determining semver pre…~~ Build data is not used when determining instance sequence Jul 7, 2025

paigecalvert commented Jul 7, 2025

View reviewed changes

docs/vendor/releases-about.mdx Show resolved Hide resolved

paigecalvert commented Jul 7, 2025

View reviewed changes

docs/vendor/releases-about.mdx Show resolved Hide resolved

paigecalvert commented Jul 7, 2025

View reviewed changes

docs/vendor/releases-about.mdx Show resolved Hide resolved

paigecalvert commented Jul 7, 2025

View reviewed changes

docs/vendor/releases-creating-channels.md Show resolved Hide resolved

paigecalvert commented Jul 7, 2025

View reviewed changes

docs/vendor/releases-about.mdx Show resolved Hide resolved

paigecalvert requested a review from banjoh July 7, 2025 21:06

banjoh reviewed Jul 8, 2025

View reviewed changes

docs/vendor/releases-about.mdx Outdated Show resolved Hide resolved

edits

1d5a906

paigecalvert force-pushed the 126246 branch from ca83cec to 1d5a906 Compare July 8, 2025 18:15

paigecalvert commented Jul 8, 2025

View reviewed changes

paigecalvert requested a review from banjoh July 8, 2025 18:31

banjoh approved these changes Jul 9, 2025

View reviewed changes

paigecalvert merged commit 0eff97f into main Jul 9, 2025
5 checks passed

paigecalvert deleted the 126246 branch July 9, 2025 15:57


		## How the Admin Console Determines Version Precedence

		The Admin Console uses version precedence to determine which versions are available for upgrade. Version precedence also determines the order in which versions are displayed on the Version history page, as shown in the example below:

Build data is not used when determining instance sequence #3363

Build data is not used when determining instance sequence #3363

Uh oh!

Conversation

paigecalvert commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for replicated-docs ready!

Uh oh!

netlify bot commented Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for replicated-docs-upgrade ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

paigecalvert Jul 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

paigecalvert commented Jul 7, 2025 •

edited

Loading

netlify bot commented Jul 7, 2025 •

edited

Loading

netlify bot commented Jul 7, 2025 •

edited

Loading

paigecalvert Jul 8, 2025 •

edited

Loading